<!-- Copyright 2005 Blandware (http://www.blandware.com) -->
<html>
<head>
</head>
<body>
    <p>
This package contains interfaces and classes implementing tags which allow to
use context menus.
    </p>
    <p>
When you want to add a context menu to your page, you need to use
<code>contextMenu</code> tag. Context menu (as rendered) consists of menu items,
each of them may be a submenu or 'end' item, clicking on which will cause some
URL to be invoked. Context menu support tags where developed to be used with
grids, so they allow to create such context menu, that its structure will be
similar for different grid rows, but right mouse button click on a row will
cause the appearance of context menu for that concrete row.
    </p>
    <p>
Whole context menu is marked with <code>contextMenu</code> tag. If you want to
build a context menu for each row (or element) in some structure, you will
probably use some iteration tag inside <code>contextMenu</code> tag (like
<code>atleap:rowsIterator</code>). Inside it, all context menu tags need to be
contained in <code>itemSet</code>. This is because tags need to know where
current set of items (the set that belongs to single data row) ends.
    </p>
    <p>
Inside <code>itemSet</code> tag, there can be <code>item</code> tags. Each of
them may render to 2 targets. First of those targets is context menu itself. Here,
<code>itemLink</code> will define the URL that corresponds to this context menu
item, <code>itemLabel</code> will generate a label that will be shown for that
context menu item. Second target is page on which context menu is rendered.
<code>itemLink</code> will produce a hyperlink, while <code>itemLabel</code>
will be ignored.
    </p>
    <p>
<code>item</code> tag has 'enabled' property. This determines how tag body
will be rendered: when <code>enabled="true"</code>, child <code>itemEnabled</code>
body will be used, otherwise <code>itemDisabled</code> will be rendered. (See
<a href="#dist">below</a> for a full list of distinctions between enabled and
disabled items).
    </p>
    <p>
Note, that content of <code>itemEnabled</code> or <code>itemDisabled</code> will
be rendered independently for context menu and for page, so it can be processed
TWICE for one menu item.
    </p>
    <p>
<code>item</code> tag may be configured to ignore some targets: when
<code>includeInContextMenu="false"</code>, this menu item will not be included
in context menu. When <code>includeInPage="false"</code>, nothing will be
rendered to page.
    </p>
    <p>
To sum up, each context menu item may be in one of following states:
<em>enabled</em>, <em>disabled</em> and <em>hidden</em>. First two correspond
to item that has corresponding <b>enabled</b> attribute and
<code>includeInContextMenu="true"</code>. Hidden context menu item is such that
has <code>includeInContextMenu="false"</code>.
    </p>
    <p>
    <a name="dist"></a>
Enabled and disabled items have following distinctions:
    <ul>
        <li>
for enabled item, <code>itemEnabled</code> is rendered, for disabled item --
<code>itemDisabled</code> is used
        </li>
        <li>
different styles are used for DIVs that will represent menu items in context
menu: by default classes named 'contextMenuItem' and
'highlightedContextMenuItem' for enabled items and 'disabledContextMenuItem'
and 'highlightedDisabledContextMenuItem' for disabled items are used
        </li>
        <li>
for disabled item, link for <code>itemLink</code> tag will not be generated when
rendering to page (but body of <code>itemLink</code> tag will be rendered)
        </li>
    </ul>
    </p>
    <p>
Here's an example:
<pre>
&lt;table&gt;
    &lt;atleap:contextMenu var=&quot;listId&quot;&gt;
        &lt;atleap:rowsIterator collection=&quot;${someList}&quot; var=&quot;element&quot; oddClass=&quot;oddRow&quot; evenClass=&quot;evenRow&quot; indexId=&quot;index&quot; firstRowEven=&quot;false&quot;&gt;
            &lt;atleap:itemSet&gt;
                &lt;tr class=&quot;${rowClass}&quot; oncontextmenu=&quot;return showContextMenu(${listId}, event, ${index});&quot;&gt;
                    &lt;td&gt;
                        First cell content
                    &lt;/td&gt;
                    &lt;atleap:item includeInContextMenu=&quot;false&quot;&gt;
                        &lt;td align=&quot;center&quot; width=&quot;20&quot; height=&quot;20&quot; valign=&quot;middle&quot;&gt;
                            &lt;atleap:itemEnabled&gt;
                                &lt;atleap:itemLink action=&quot;action1&quot;&gt;
                                    &lt;img src=&quot;picture1&quot; /&gt;
                                    &lt;atleap:itemLabel&gt;
                                        Text that will never be shown
                                    &lt;/atleap:itemLabel&gt;
                                &lt;/atleap:itemLink&gt;
                            &lt;/atleap:itemEnabled&gt;
                        &lt;/td&gt;
                    &lt;/atleap:item&gt;
                    &lt;atleap:item includeInPage=&quot;false&quot;&gt;
                        &lt;atleap:itemEnabled&gt;
                            &lt;atleap:itemLink&gt;
                                &lt;atleap:itemLabel&gt;
                                    Content that will be a label for submenu
                                &lt;/atleap:itemLabel&gt;
                            &lt;/atleap:itemLink&gt;
                        &lt;/atleap:itemEnabled&gt;
                        &lt;atleap:item includeInPage=&quot;false&quot;&gt;
                            &lt;atleap:itemEnabled&gt;
                                &lt;atleap:itemLink action=&quot;action2/1&quot;&gt;
                                    &lt;img src=&quot;picture2/1&quot; /&gt;
                                    &lt;atleap:itemLabel&gt;
                                        Label of first menu item in submenu
                                    &lt;/atleap:itemLabel&gt;
                                &lt;/atleap:itemLink&gt;
                            &lt;/atleap:itemEnabled&gt;
                        &lt;/atleap:item&gt;
                        &lt;atleap:item includeInPage=&quot;false&quot;&gt;
                            &lt;atleap:itemEnabled&gt;
                                &lt;atleap:itemLink action=&quot;action2/2&quot;&gt;
                                    &lt;img src=&quot;picture2/2&quot; /&gt;
                                    &lt;atleap:itemLabel&gt;
                                        Label of second menu item in submenu
                                    &lt;/atleap:itemLabel&gt;
                                &lt;/atleap:itemLink&gt;
                            &lt;/atleap:itemEnabled&gt;
                        &lt;/atleap:item&gt;
                        &lt;atleap:item includeInPage=&quot;false&quot;&gt;
                            &lt;atleap:itemEnabled&gt;
                                &lt;atleap:itemLink action=&quot;action2/3&quot;&gt;
                                    &lt;img src=&quot;picture2/3&quot; /&gt;
                                    &lt;atleap:itemLabel&gt;
                                        Label of third menu item in submenu
                                    &lt;/atleap:itemLabel&gt;
                                &lt;/atleap:itemLink&gt;
                            &lt;/atleap:itemEnabled&gt;
                        &lt;/atleap:item&gt;
                    &lt;/atleap:item&gt;
                    &lt;c:set var=&quot;enabled&quot; value=&quot;${someExpression}&quot; /&gt;
                    &lt;atleap:item enabled=&quot;${enabled}&quot;&gt;
                        &lt;td align=&quot;center&quot; width=&quot;20&quot; height=&quot;20&quot; valign=&quot;middle&quot;&gt;
                            &lt;atleap:itemEnabled&gt;
                                &lt;atleap:itemLink action=&quot;action3/enabled&quot;&gt;
                                    &lt;atleap:param name=&quot;paramName&quot; value=&quot;${paramExpr}&quot; /&gt;
                                    &lt;img src=&quot;picture3/enabled&quot; /&gt;
                                    &lt;atleap:itemLabel&gt;
                                        Label for enabled menu item
                                    &lt;/atleap:itemLabel&gt;
                                &lt;/atleap:itemLink&gt;
                            &lt;/atleap:itemEnabled&gt;
                            &lt;atleap:itemDisabled&gt;
                                &lt;atleap:itemLink title=&quot;This menu item is disabled; we don't supply it with 'action'&quot;&gt;
                                    &lt;img src=&quot;picture3/disabled&quot; /&gt;
                                    &lt;atleap:itemLabel&gt;
                                        Label for disabled menu item
                                    &lt;/atleap:itemLabel&gt;
                                &lt;/atleap:itemLink&gt;
                            &lt;/atleap:itemDisabled&gt;
                        &lt;/td&gt;
                    &lt;/atleap:item&gt;
                    &lt;atleap:item&gt;
                        &lt;td align=&quot;center&quot; width=&quot;20&quot; height=&quot;20&quot; valign=&quot;middle&quot;&gt;
                            &lt;atleap:itemEnabled&gt;
                                &lt;atleap:itemLink action=&quot;action4&quot; title=&quot;someText&quot;&gt;
                                    &lt;img src=&quot;picture4&quot; /&gt;
                                    &lt;atleap:itemLabel&gt;
                                        One more label
                                    &lt;/atleap:itemLabel&gt;
                                &lt;/atleap:itemLink&gt;
                            &lt;/atleap:itemEnabled&gt;
                        &lt;/td&gt;
                    &lt;/atleap:item&gt;
                &lt;/tr&gt;
            &lt;/atleap:itemSet&gt;
        &lt;/atleap:rowsIterator&gt;
    &lt;/atleap:contextMenu&gt;
&lt;/table&gt;
</pre>
This code will generate a table from a list of some elements, that list will be
taken from ${someList}. For each element in list a row will be produced. First
cell of row will contain text 'First cell content'. Second cell will have
an image with <code>src='picture1'</code>; it will not have corresponding
context menu item, because <code>includeInContextMenu="false"</code>. Next
<code>item</code> will not generate anything to page, but only to context menu.
This will be a submenu consisting of 3 menu items. Label of submenu will be
'Content that will be a label for submenu'. Note, that menu items that are owned
by submenu are nested directly in <code>item</code> tag, not in
<code>itemEnabled</code>, for example.
    </p>
    <p>
Then, there's an <code>item</code> that is enabled depending on
${someExpression} expression. If it's disabled, corresponding menu item will
not be pressable. Note, that this effect is achieved with following: <b>action</b>
attribute, that belongs to <code>itemLink</code> tag, is not specified. So,
if we would like, we could set some <b>action</b> (or <b>forward</b>, or
<b>href</b>) and get 'disabled' item, that would be pressable.
    </p>
</body>
</html>